docs: Add AGENTS.md with repository instructions for AI tooling#1516
docs: Add AGENTS.md with repository instructions for AI tooling#1516mhmohona wants to merge 15 commits intomunich-quantum-toolkit:mainfrom
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@AGENTS.md`:
- Line 41: The current line referencing the command "nox -s docs -- -b html" in
AGENTS.md incorrectly implies it also serves content; update the wording to
state explicitly that this command only builds the HTML and does not start a web
server, and add a follow-up sentence instructing readers to run a simple local
HTTP server to preview the built docs (mention common options like using
Python's built-in http.server or a small Node/static server) so users know they
must run a separate serve step.
|
Thanks for your interest in contributing to the project as part of unitaryDESIGN! Generally, it would be great if you could comment on the respective issue (#1459) to indicate that you are working on this issue. Otherwise, there is no way that we could assign the issue to you, if your solution should be accepted. There is a competing solution in #1518 that seems a little more extensive than the one being proposed here, so I am slightly leaning towards that at the moment, but this is definitely not a definitive decision. |
burgholzer
added
documentation
denialhaag
left a comment
denialhaag
left a comment
There was a problem hiding this comment.
Hi, @mhmohona! Thanks a lot for the proposal! 🙂
I have gone through everything now and left a couple of suggestions. Regarding the comment by @burgholzer, I explicitly did not comment on information that may still be missing, and leave that up to your judgment.
Co-authored-by: Daniel Haag <121057143+denialhaag@users.noreply.github.com> Signed-off-by: Mahfuza Humayra Mohona <mhmohona@gmail.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Mahfuza Humayra Mohona <mhmohona@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Line 11: Change the "For C++ only:" prefix to use an em dash with surrounding
spaces for typographic consistency in the AGENTS.md line containing "For C++
only: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
-DBUILD_MQT_CORE_TESTS=ON`, then `cmake --build build` — replace the colon with
" — " so the line reads e.g. "For C++ only — `cmake -S . -B build
-DCMAKE_BUILD_TYPE=Release -DBUILD_MQT_CORE_TESTS=ON`, then `cmake --build
build`".
- Around line 34-35: The three consecutive sentences in AGENTS.md that start
with "We use" (the lines mentioning `clang-format`/`clang-tidy` and `typos`) are
repetitive; rewrite them to vary sentence openings and improve flow by combining
related tooling into one sentence or using different constructions (e.g., "For
C++ formatting and linting, we rely on `clang-format` and `clang-tidy`" and
"Spell checking across the codebase is performed with `typos`"), updating the
sentences that mention `clang-format`, `clang-tidy`, and `typos`.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Mahfuza Humayra Mohona <mhmohona@gmail.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Mahfuza Humayra Mohona <mhmohona@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Line 12: Update the Platform line that currently reads "**Platform**:
Operating in a Linux environment with support for x86_64 (amd64) and arm64." to
reflect all target OSes and architectures by changing it to something like
"**Platform**: Operating on Linux, macOS, and Windows with support for x86_64
(amd64) and arm64." Ensure the revised sentence replaces the existing platform
line in AGENTS.md so it matches the project platform scope.
- Line 13: AGENTS.md currently states "3.10–3.14" which wrongly implies an upper
bound; update the Python version wording to reflect the actual constraint
(requires-python = ">=3.10") by replacing "3.10–3.14" with "3.10+" (or
alternatively list only CI-tested versions), and ensure any mention of
conditional dependencies for 3.14 remains separate; edit the AGENTS.md string
"3.10–3.14" so it matches the project requirement and does not imply support up
to 3.14.
|
|
||
| ## Environment & Capabilities | ||
|
|
||
| - **Platform**: Operating in a Linux environment with support for x86_64 (amd64) and arm64. |
There was a problem hiding this comment.
Platform scope contradicts the project target platforms.
Line 12 says Linux-only, but the objective requires Linux, macOS, and Windows for x86 and arm64. Please align this line with the stated platform targets.
✍️ Suggested update
-- **Platform**: Operating in a Linux environment with support for x86_64 (amd64) and arm64.
+- **Platform**: Target Linux, macOS, and Windows for x86_64 (amd64) and arm64.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Platform**: Operating in a Linux environment with support for x86_64 (amd64) and arm64. | |
| - **Platform**: Target Linux, macOS, and Windows for x86_64 (amd64) and arm64. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` at line 12, Update the Platform line that currently reads
"**Platform**: Operating in a Linux environment with support for x86_64 (amd64)
and arm64." to reflect all target OSes and architectures by changing it to
something like "**Platform**: Operating on Linux, macOS, and Windows with
support for x86_64 (amd64) and arm64." Ensure the revised sentence replaces the
existing platform line in AGENTS.md so it matches the project platform scope.
✅ Addressed in commit 0b96a4a
There was a problem hiding this comment.
@coderabbitai is correct. We also support macOS and Windows.
There was a problem hiding this comment.
@denialhaag, thank you for confirming! I'll keep the suggestion as-is so the platform line can be updated to reflect all three target operating systems (Linux, macOS, and Windows) along with the x86_64 and arm64 architectures. 🐰
(\/)
(^.^)
c(")_(")
(happy to help!)
🧠 Learnings used
Learnt from: DRovara
Repo: munich-quantum-toolkit/core PR: 1108
File: mlir/lib/Dialect/MQTOpt/Transforms/ReplaceBasisStateControlsWithIfPattern.cpp:219-221
Timestamp: 2025-10-09T13:14:10.178Z
Learning: The MQT Core project (munich-quantum-toolkit/core repository) uses the C++20 standard, not C++17. C++20 features such as abbreviated function templates (e.g., `const auto&` parameters) are supported and valid in this codebase.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1403
File: src/qdmi/na/CMakeLists.txt:31-38
Timestamp: 2025-12-28T17:14:53.890Z
Learning: In the munich-quantum-toolkit/core repository, the NA device generator target (mqt-core-qdmi-na-device-gen) is intentionally propagated to MQT_CORE_TARGETS via list(APPEND) because it's publicly linked to the NA device library (the NA device uses a public function from the generator). The SC device generator is not propagated because it has no such dependency with the SC device library.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1355
File: bindings/fomac/fomac.cpp:227-264
Timestamp: 2025-12-07T01:21:27.544Z
Learning: In the munich-quantum-toolkit/core repository, docstrings for Python bindings are added to the corresponding stub files (.pyi) rather than directly in the pybind11 C++ bindings code. This practice may change if the project adopts nanobind with automatic stub generation.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1356
File: src/qdmi/na/CMakeLists.txt:179-184
Timestamp: 2026-01-04T23:54:33.540Z
Learning: In the munich-quantum-toolkit/core repository, MSVC link-time code generation (LTCG) must be disabled for the NA device dynamic library target (mqt-core-qdmi-na-device-dyn) on Windows to avoid link errors and missing symbols. This issue affects both release-only builds and debug/release mixed builds, not just debug/release mixing scenarios.
Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1360
File: .github/workflows/reusable-mlir-tests.yml:40-43
Timestamp: 2025-12-05T17:45:37.602Z
Learning: In the munich-quantum-toolkit/core repository, patch releases of LLVM dependencies don't require documentation updates, changelog entries, or additional tests beyond what's validated by passing CI checks.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1355
File: src/qdmi/sc/Device.cpp:97-102
Timestamp: 2025-12-07T09:10:31.836Z
Learning: In the munich-quantum-toolkit/core repository, duplication of QDMI-related macros (such as IS_INVALID_ARGUMENT) across device implementations (e.g., in src/qdmi/sc/Device.cpp and src/qdmi/dd/Device.cpp) is acceptable as a temporary measure. The preferred long-term solution is to upstream these macros to the QDMI repository rather than creating local shared headers, so they can be reused across all dependent projects.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1246
File: bindings/CMakeLists.txt:0-0
Timestamp: 2025-10-10T08:09:54.528Z
Learning: In the Munich Quantum Toolkit (MQT) Core project, scikit-build-core is configured with `wheel.install-dir = "mqt/core"` in pyproject.toml, which automatically prefixes all CMake `DESTINATION` paths with `mqt/core/` during wheel installation. Therefore, CMake install destinations are relative to the `mqt/core` package namespace, not `site-packages`.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1356
File: cmake/SetupMLIR.cmake:32-33
Timestamp: 2026-01-04T21:41:30.252Z
Learning: In the munich-quantum-toolkit/core repository, the project provides its own pre-built LLVM/MLIR distributions that are compiled with LLVM_ENABLE_RTTI=ON and LLVM_ENABLE_EH=ON. Users are directed to these distributions via the upgrade guide and installation instructions to avoid ABI compatibility issues. The mid-term goal is to eliminate RTTI and exception handling dependencies entirely.
Learnt from: flowerthrower
Repo: munich-quantum-toolkit/core-plugins-catalyst PR: 1
File: CHANGELOG.md:18-18
Timestamp: 2025-12-01T11:00:40.342Z
Learning: In the munich-quantum-toolkit/core-plugins-catalyst repository, the CHANGELOG.md intentionally references the parent MQT Core repository's release notes (https://github.com/munich-quantum-toolkit/core/releases) because the plugin repository is based on work performed in the parent repository.
There was a problem hiding this comment.
@mhmohona there must have been some kind of regression, because this was fixed at some point, but now it isn't and the comment from @coderabbitai is still open.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check the current content of AGENTS.md, specifically around line 12
cat AGENTS.md | head -n 15 | tail -n 8
Length of output: 453
@burgholzer, you're absolutely right—Line 12 still shows "Operating in a Linux environment" only, without mentioning macOS and Windows. The fix hasn't been applied to the current version.
@mhmohona, could you please update Line 12 to reflect all target platforms? The line should read something like:
- **Platform**: Target Linux, macOS, and Windows for x86_64 (amd64) and arm64.
This ensures the AGENTS.md accurately describes the project's multi-platform support.
🧠 Learnings used
Learnt from: DRovara
Repo: munich-quantum-toolkit/core PR: 1108
File: mlir/lib/Dialect/MQTOpt/Transforms/ReplaceBasisStateControlsWithIfPattern.cpp:219-221
Timestamp: 2025-10-09T13:14:10.178Z
Learning: The MQT Core project (munich-quantum-toolkit/core repository) uses the C++20 standard, not C++17. C++20 features such as abbreviated function templates (e.g., `const auto&` parameters) are supported and valid in this codebase.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1403
File: src/qdmi/na/CMakeLists.txt:31-38
Timestamp: 2025-12-28T17:14:53.890Z
Learning: In the munich-quantum-toolkit/core repository, the NA device generator target (mqt-core-qdmi-na-device-gen) is intentionally propagated to MQT_CORE_TARGETS via list(APPEND) because it's publicly linked to the NA device library (the NA device uses a public function from the generator). The SC device generator is not propagated because it has no such dependency with the SC device library.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1355
File: bindings/fomac/fomac.cpp:227-264
Timestamp: 2025-12-07T01:21:27.544Z
Learning: In the munich-quantum-toolkit/core repository, docstrings for Python bindings are added to the corresponding stub files (.pyi) rather than directly in the pybind11 C++ bindings code. This practice may change if the project adopts nanobind with automatic stub generation.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1356
File: src/qdmi/na/CMakeLists.txt:179-184
Timestamp: 2026-01-04T23:54:33.540Z
Learning: In the munich-quantum-toolkit/core repository, MSVC link-time code generation (LTCG) must be disabled for the NA device dynamic library target (mqt-core-qdmi-na-device-dyn) on Windows to avoid link errors and missing symbols. This issue affects both release-only builds and debug/release mixed builds, not just debug/release mixing scenarios.
Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1360
File: .github/workflows/reusable-mlir-tests.yml:40-43
Timestamp: 2025-12-05T17:45:37.602Z
Learning: In the munich-quantum-toolkit/core repository, patch releases of LLVM dependencies don't require documentation updates, changelog entries, or additional tests beyond what's validated by passing CI checks.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1355
File: src/qdmi/sc/Device.cpp:97-102
Timestamp: 2025-12-07T09:10:31.836Z
Learning: In the munich-quantum-toolkit/core repository, duplication of QDMI-related macros (such as IS_INVALID_ARGUMENT) across device implementations (e.g., in src/qdmi/sc/Device.cpp and src/qdmi/dd/Device.cpp) is acceptable as a temporary measure. The preferred long-term solution is to upstream these macros to the QDMI repository rather than creating local shared headers, so they can be reused across all dependent projects.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1246
File: bindings/CMakeLists.txt:0-0
Timestamp: 2025-10-10T08:09:54.528Z
Learning: In the Munich Quantum Toolkit (MQT) Core project, scikit-build-core is configured with `wheel.install-dir = "mqt/core"` in pyproject.toml, which automatically prefixes all CMake `DESTINATION` paths with `mqt/core/` during wheel installation. Therefore, CMake install destinations are relative to the `mqt/core` package namespace, not `site-packages`.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1356
File: cmake/SetupMLIR.cmake:32-33
Timestamp: 2026-01-04T21:41:30.252Z
Learning: In the munich-quantum-toolkit/core repository, the project provides its own pre-built LLVM/MLIR distributions that are compiled with LLVM_ENABLE_RTTI=ON and LLVM_ENABLE_EH=ON. Users are directed to these distributions via the upgrade guide and installation instructions to avoid ABI compatibility issues. The mid-term goal is to eliminate RTTI and exception handling dependencies entirely.
Learnt from: flowerthrower
Repo: munich-quantum-toolkit/core-plugins-catalyst PR: 1
File: CHANGELOG.md:18-18
Timestamp: 2025-12-01T11:00:40.342Z
Learning: In the munich-quantum-toolkit/core-plugins-catalyst repository, the CHANGELOG.md intentionally references the parent MQT Core repository's release notes (https://github.com/munich-quantum-toolkit/core/releases) because the plugin repository is based on work performed in the parent repository.
Learnt from: taminob
Repo: munich-quantum-toolkit/core PR: 1206
File: mlir/lib/Dialect/QCO/IR/CMakeLists.txt:52-54
Timestamp: 2026-02-08T14:04:59.274Z
Learning: In the munich-quantum-toolkit/core repository's MLIR dialect (mlir/lib/Dialect/QCO/IR/CMakeLists.txt), the MLIRQCODialect target uses `target_compile_definitions(MLIRQCODialect PUBLIC EIGEN_MAX_STATIC_ALIGN_BYTES=16)` to work around stack alignment issues on x86_64 with AVX. When AVX is enabled, Eigen expects 32-byte alignment for types like Eigen::Matrix2cd, but the compiler only guarantees 16-byte stack alignment for automatic variables, causing segfaults. This setting forces Eigen to use 16-byte alignment, trading vectorization performance for correctness. The PUBLIC scope is necessary because this is a library-wide alignment constraint.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1326
File: python/mqt/core/__init__.py:22-22
Timestamp: 2025-11-24T10:19:41.147Z
Learning: In the munich-quantum-toolkit/core repository, Ruff is configured with 'ALL' rules enabled by default, and only specific rules are selectively disabled. When reviewing changes that enable previously-disabled rules (like PLC0415), noqa directives for those rules become necessary and should be retained.
Learnt from: burgholzer
Repo: munich-quantum-toolkit/qcec PR: 831
File: bindings/register_equivalence_checking_manager.cpp:11-20
Timestamp: 2026-01-26T00:52:09.661Z
Learning: In munich-quantum-toolkit (MQT) projects, Python bindings targets are not built by default in CI workflows. This can cause clang-tidy to miss issues in bindings code (e.g., missing includes, type errors) because clang-tidy requires the code to be compiled to generate a compilation database for analysis. To enable linting of bindings code, add `-DBUILD_MQT_QCEC_BINDINGS=ON` (or the equivalent flag for other MQT packages like `-DBUILD_MQT_CORE_BINDINGS=ON`) to the cmake-args in the linter action workflow.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Mahfuza Humayra Mohona <mhmohona@gmail.com>
There was a problem hiding this comment.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@AGENTS.md`:
- Line 13: Update the Python version wording under the "Python Context" line
that currently reads “3.10–3.14” to avoid implying an upper bound; change it to
“3.10+” (or alternatively list only the CI-tested versions) so the docs reflect
the project minimum requirement—edit the AGENTS.md entry for the "Python
Context" line to replace “3.10–3.14” with the chosen phrasing.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 33-34: Replace the colon after "Configure Release build" and
"Configure Debug build" with an em dash (—) for consistent em-dash style in the
two bullet lines; edit the two lines that currently read "Configure Release
build: `...`" and "Configure Debug build: `...`" to use an em dash before the
inline code block instead of a colon.
---
Duplicate comments:
In `@AGENTS.md`:
- Line 12: Update the platform scope line that currently reads "**Platform**:
Operating in a Linux environment with support for x86_64 (amd64) and arm64." to
include macOS and Windows as supported OSes for both x86_64 (amd64) and arm64
architectures; locate the exact "**Platform**" line in AGENTS.md and revise it
to mention Linux, macOS, and Windows with the supported architectures
(x86_64/amd64 and arm64).
- Around line 63-68: The bullet list in AGENTS.md repeats the word "Use" at the
start of six consecutive bullets, creating a stilted rhythm; rewrite the bullets
to vary sentence structure and improve flow by alternating sentence starts
(e.g., "Prefer uv as the mandatory package manager", "Adopt nanobind (~2.11.0)
for Python bindings instead of pybind11", "Ruff is required for
linting/formatting with ALL rules enabled", "Replace mypy with ty for static
type checking", "Target LLVM 21.1+ for MLIR-based compilation dialects", and
"Apply clang-format and typos for C++ style and spell checking"), preserving the
same requirements and versions exactly.
| - Configure Release build: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_MQT_CORE_TESTS=ON`. | ||
| - Configure Debug build: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_MQT_CORE_TESTS=ON`. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Optional: Em dash style for consistency.
The static analysis tool suggests using em dashes (—) instead of colons for enumeration consistency. This is purely a stylistic preference and the current format is perfectly clear.
✍️ Optional style improvement
-- Configure Release build: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_MQT_CORE_TESTS=ON`.
-- Configure Debug build: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_MQT_CORE_TESTS=ON`.
+- Configure Release build — `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_MQT_CORE_TESTS=ON`.
+- Configure Debug build — `cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_MQT_CORE_TESTS=ON`.🧰 Tools
🪛 LanguageTool
[typographical] ~33-~33: Consider using an em dash and a white space in dialogues and enumerations.
Context: ...+ Workflows - Configure Release build: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUI...
(DASH_RULE)
[typographical] ~34-~34: Consider using an em dash and a white space in dialogues and enumerations.
Context: ...ORE_TESTS=ON. - Configure Debug build: cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD...
(DASH_RULE)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 33 - 34, Replace the colon after "Configure Release
build" and "Configure Debug build" with an em dash (—) for consistent em-dash
style in the two bullet lines; edit the two lines that currently read "Configure
Release build: `...`" and "Configure Debug build: `...`" to use an em dash
before the inline code block instead of a colon.
denialhaag
left a comment
denialhaag
left a comment
There was a problem hiding this comment.
Thanks a lot for addressing my comments! 🙂
I propose leaving this PR open alongside #1518 so that other contributors (in particular, @burgholzer) can review your changes.
burgholzer
left a comment
burgholzer
left a comment
There was a problem hiding this comment.
Thanks @mhmohona for your interest in contributing towards this issue! 🙏🏼 much appreciated.
I gave this a pretty thorough review now and left a ton of comments. These should get you quite far already.
In essence, this file needs to be curated better.
There should be no redundant information in the file as this is information that most models will read for basically every session, and it eats from the context window.
As such, it also needs to be as precise as possible and should not offer alternatives for doing things, but state very clearly the commands to be performed for certain tasks.
The remarks/notes/comments, should also be less descriptive, but really actionable, for example, clearly stating that uvx nox -s lint shall be run after changes and that these need to pass.
| # MQT Core | ||
|
|
||
| - Acts as the high-performance backbone for the [Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io/). | ||
| - Provides core data structures and algorithms (IR, DD, ZX, QASM 3.0, MLIR) for quantum design automation. |
There was a problem hiding this comment.
| - Provides core data structures and algorithms (IR, DD, ZX, QASM 3.0, MLIR) for quantum design automation. | |
| - Provides tools and methods (IRs, DD, ZX, OpenQASM, MLIR, QIR, QDMI, NA, Qiskit, etc.) for quantum design automation, including simulation, compilation, verification as well as HPCQC integration. |
Trying to rephrase this a little.
|
|
||
| - Acts as the high-performance backbone for the [Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io/). | ||
| - Provides core data structures and algorithms (IR, DD, ZX, QASM 3.0, MLIR) for quantum design automation. | ||
| - Distinguishes between **circuit qubits** (logical/virtual) and **device qubits** (physical) to avoid ambiguity. |
There was a problem hiding this comment.
| - Distinguishes between **circuit qubits** (logical/virtual) and **device qubits** (physical) to avoid ambiguity. |
Feels overly detailed and not too important for most day to day use.
| - Provides core data structures and algorithms (IR, DD, ZX, QASM 3.0, MLIR) for quantum design automation. | ||
| - Distinguishes between **circuit qubits** (logical/virtual) and **device qubits** (physical) to avoid ambiguity. | ||
| - Maintains a C++20 core with an architecturally separate Python extension layer. | ||
| - Locates C++ sources in `src/` and `include/`, Python bindings in `python/`, tests in `test/`, and documentation in `docs/`. |
There was a problem hiding this comment.
This is not fully correct and complete.
Yes, most of the C++ code is in src and include, but the entire MLIR codebase is under mlir.
The Python bindings actually reside in bindings, while the Python package code lives in python/mqt/core.
| - Distinguishes between **circuit qubits** (logical/virtual) and **device qubits** (physical) to avoid ambiguity. | ||
| - Maintains a C++20 core with an architecturally separate Python extension layer. | ||
| - Locates C++ sources in `src/` and `include/`, Python bindings in `python/`, tests in `test/`, and documentation in `docs/`. | ||
| - Refer to [index.md](docs/index.md) for the complete documentation entry point. |
There was a problem hiding this comment.
Given how an LLM won't be able to access a built version of the docs, this feels slightly unnecessary.
| - Refer to [index.md](docs/index.md) for the complete documentation entry point. |
|
|
||
| ## Environment & Capabilities | ||
|
|
||
| - **Platform**: Operating in a Linux environment with support for x86_64 (amd64) and arm64. |
There was a problem hiding this comment.
@mhmohona there must have been some kind of regression, because this was fixed at some point, but now it isn't and the comment from @coderabbitai is still open.
| ## Self-Review Checklist | ||
|
|
||
| - Did you run `uvx nox -s lint` and ensure all checks (ruff, typos, ty) pass? | ||
| - Did you verify all your changes with at least one automated test (pytest or ctest)? |
There was a problem hiding this comment.
| - Did you verify all your changes with at least one automated test (pytest or ctest)? | |
| - Did you verify all your changes with at least one automated test (pytest or googletest)? |
ctest is only the test runner. googletest is the framework we use for testing
|
|
||
| - Did you run `uvx nox -s lint` and ensure all checks (ruff, typos, ty) pass? | ||
| - Did you verify all your changes with at least one automated test (pytest or ctest)? | ||
| - Did you update/add tests for new functionality to maintain coverage? |
There was a problem hiding this comment.
Feels redundant with the point above.
| - Did you run `uvx nox -s lint` and ensure all checks (ruff, typos, ty) pass? | ||
| - Did you verify all your changes with at least one automated test (pytest or ctest)? | ||
| - Did you update/add tests for new functionality to maintain coverage? | ||
| - Did you use exact terminology (**circuit qubits** vs **device qubits**)? |
There was a problem hiding this comment.
| - Did you use exact terminology (**circuit qubits** vs **device qubits**)? |
Not needed based on the comment at the very top.
| - Did you use exact terminology (**circuit qubits** vs **device qubits**)? | ||
| - Did you regenerate Python stubs via `uvx nox -s stubs` if bindings were modified? | ||
| - Did you check for manual changes to `.pyi` files (which are forbidden)? | ||
| - Did you include the correct license headers and SPDX identifiers? |
There was a problem hiding this comment.
This is automatically handled by prek. no need to state this here
| - Did you include the correct license headers and SPDX identifiers? |
| ## Rules | ||
|
|
||
| - Adhere to the ruff philosophy: Start with `ALL` rules and selectively disable in `pyproject.toml`. | ||
| - Enforce term capitalization: `nanobind`, `CMake`, `ccache`, `GitHub`, `NumPy`, `pytest`, `MQT`, and `TUM`. | ||
| - Include MIT license and SPDX headers in every source file. | ||
| - Avoid modifying templated files locally; contribute to [MQT templates](https://github.com/munich-quantum-toolkit/templates). | ||
| - Verify all CI checks locally; if `uvx nox -s lint` fails, the code is not ready for PR. |
There was a problem hiding this comment.
This feels like it is repeating some information from above incompletely.
3 participants
Description
Adds AGENTS.md file to provide repository instructions for AI coding agents (Copilot, Claude Code, Cursor, CodeRabbit, etc.).
The file follows the AGENTS.md format — concise, bullet-point-driven instructions optimized for agent consumption. The Ruff CLAUDE.md and apache airflow AGENTS.md was used as additional inspiration for the development guidelines section, as suggested in the issue.
Fixes #1459
Checklist: